package bmaso.purest.operation;

import javax.servlet.jsp.PageContext;

/**
 * <p>
 * Abstract description of a logical operation: an invocable object
 * that may modify the state of a system, and may return output values.
 * In the sense of Operation State Modeling, an operation on a system
 * takes some input set of values, and returns an output set of
 * values. The state of the system is an additional implicit input
 * to the operation, and the final state of the system is an
 * implicit output to the operation.
 * </p>
 * 
 * <p>
 * The result of an operation invocation is either success, or
 * failure. In the case of success, the post-conditions of the
 * operation's definition guaranteed to be preserved. Failures
 * occur because the preconditions of the operation have not been
 * met.
 * </p>
 * 
 * <p>
 * Typically a service operation returns its output value(s) in the
 * PageContext.
 * </p>
 * 
 * @throws IllegalArgumentException Thrown if a precondition
 *     failure is found. This is either a statically-defined or
 *     dynamically defined precondition rule violation.
 * 
 * @throws IllegalStateException Thrown if the precondition
 *     failure involves solely an aspec of the system state. That
 *     is, in its current state the system cannot execute the operation
 *     irrespective of the <i>opInput</i> input values.
 */
public interface ServiceOperation {
	public Object invoke(PageContext pageContext, Object... opInput)
			throws IllegalArgumentException, IllegalStateException;
}
